<!DOCTYPE html>

<html>
<head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
    <title>Plugins - Raxan User Guide</title>
    <link href="../raxan/ui/css/master.css" rel="stylesheet" type="text/css" />
    <!--[if lt IE 8]> <link rel="stylesheet" href="../raxan/ui/css/master.ie.css" type="text/css"><![endif]-->
    <link href="../raxan/ui/css/default/theme.css" rel="stylesheet" type="text/css" />
    <link href="style.css" rel="stylesheet" type="text/css" />
    <link href="highlight/styles/default.css" rel="stylesheet" type="text/css" />
    <script type="text/javascript" src="highlight/highlight.js"></script>
    <script type="text/javascript">
        <!--
        hljs.initHighlightingOnLoad('javascript','html','php','css');
        //-->
    </script>
    <!--[if lt IE 7]>
        <style type="text/css"> form input.textbox { height: 26px; }</style>
    <![endif]-->
</head>

<body>
    <div class="container">
        <div id="header" class="rax-header-pal rax-metalic">
            <h2 class="ltm bottom c14">Raxan User Guide</h2>
            <ul>
                <li><a href="../../index.html">Home</a></li>
                <li><a href="index.html">Overview</a></li>
                <li><a href="features.html">Features</a></li>
                <li><a href="table-of-contents.html" title="Table of Content">Contents</a></li>
                <li><a href="../examples">Examples</a></li>
            </ul>
            <ul class="search">
                <li>
                    <form class="tpm c9" name="form1" action="../tools/search.php" method="get">
                        <input class="c6 textbox round left" placeholder="Search" type="text" name="q" value="" title="Search User Guide"  />
                        <input class="c2 button round left ltm" type="submit" value="Go" />
                    </form>
                </li>
            </ul>

        </div>
        <hr class="space"/>
        <div class="master-content-wrapper">
            <div class="container prepend-top c48 master-content"><h2>Plugins &amp; System Events</h2>

<p>Plugins are special classes that are used to extend the framework by listening to or interacting with system-events or making system wide changes. For 
example, you can create a plugin to add a footnote to every page within your web site without having to directly modify the individual pages.</p>

<h3>Creating a Plugin</h3>

<p>To create a plugin you need to extend the RaxanPlugin class as shown below:</p>

<pre><code class="php">&lt;?php
    class NewPlugin extends RaxanPlugin {
        public static $name = 'New Plugin';
        public static $description = "Plugin descrtion goes here";
        public static $author = "Author's Name";
        protected function methods() { return get_class_methods($this); }
        public static function register() { return self::instance(__CLASS__); }

        protected function myMethodName() {
            // your method code here
        }

        public function doSomething() {
            // your method code here
        }
    }
    NewPlugin::register(); // register the plugin
?&gt;
</code></pre>

<p>Next, you will need to add system event handler methods to your plugin so that you can perform an action when the event is invoked:</p>

<pre><code class="php">&lt;?php
    class NewPlugin extends RaxanPlugin {
        public static $name = 'New Plugin';
        public static $description = "Plugin descrtion goes here";
        public static $author = "Author's Name";
        protected function methods() { return get_class_methods($this); }
        public static function register() { return self::instance(__CLASS__); }

        protected function page_load($e, $page) {
            $page-&gt;append('Hello from Plugin!'); // append the text to the web page
        }

        protected function myMethodName() {
            // your method code here
        }

        public function doSomething() {
            // your method code here
        }
    }
    NewPlugin::register(); // register the plugin

?&gt;
</code></pre>

<p>When you're finished you can save your plugin to the raxan plugins folder. For example you could save the file (dosomething.php) to a folder
called myplugins (raxan/plugins/myplugins).</p>

<h3>Loading a plugin</h3>

<p>There are two ways to load a plugin with Raxan. You can use either the "preload.plugins" configuration option or the call the loadPlugin() method as shown:</p>

<h4>Using the loadPlugin() method</h4>

<p>To load a plugin you simple make a call to the Raxan::loadPlugin() method:</p>

<pre><code class="php">&lt;?php
    // load plugin from plugins.path. The .php extension is not needed
    Raxan::loadPlugin('myplugins/newplugin');

    // get a reference to the loaded plugin instance
    $instance = Raxan::loadPlugin('myplugins/newplugin');
    $instance-&gt;doSeomthing(); // call public methods from the plugin

?&gt;
</code></pre>

<p>Or call the loadPlugin wrapper directly from the web page:</p>

<pre><code class="php">&lt;?php
    protected function _init() {
        // load plugin
        $this-&gt;loadPlugin('myplugins/newplugin');

        // load and get a reference to the registered plugin instance
        $instance = $this-&gt;loadPlugin('myplugins/newplugin');
        $instance-&gt;doSeomthing(); // call public methods from the plugin

        // load plugin and assign an alias to the loaded instance
        $this-&gt;loadPlugin('myplugins/newplugin','myPlugin');   // load as myPlugin property
        $this-&gt;myPlugin-&gt;doSomething(); // call public methods from myPlugin
    }
?&gt;
</code></pre>

<p>The above will load the plugin relative to the plugins.path configuration option, which defaults to the raxan/plugins folder.  Notice that we did not
have to specify the .php extension for the plugin file.</p>

<p>To load a plugin that's located inside an alternate folder (not relative to plugins.path):</p>

<pre><code class="php">&lt;?php
    // load external plugin using Raxan::loadPlugin()
    Raxan::loadPlugin('/path/to/plugin/newplugin.php', true);

    // load external plugin using RaxanWebPage-&gt;loadPlugin() and assign it to 'myPlugin' alias
    protected function _config() {
        $this-&gt;loadPlugin('/path/to/plugin/newplugin.php', true, 'myPlugin');
    }
?&gt;
</code></pre>

<p>The second parameter will cause the framework to load the plugin based on the specified folder path and filename. Please note that you will have to
include the .php extension when loading plugins that are external to the assigned 'plugins.path'.</p>

<h4>Using the preload.plugins configuration option</h4>

<p>To load your plugins at startup your can use the preload.plugins from within your config file:</p>

<pre><code class="php">&lt;?php
    // comma delimited list of plugins
    $config['preload.plugins'] = 'plugin1, plugin2, myplugins/dosomething, /path/to/plugin/name.php';
?&gt;
</code></pre>

<h3>Adding methods to a page or element</h3>

<p>In addition to listening to system events, you can also use a plugin to add new functionality to a web page to element. For example, you might want to
create a plugin that adds a userLogin() method to the page.</p>

<p>To add new methods to a page or element you can use addMethod() as follow:</p>

<pre><code class="php">&lt;?php

    // ... network-connector plugin ...

    protected function page_config($e, $page){
        // add new method to the page object
        $page-&gt;addMethod('networkUserLogin',array($this,'login'));

        // or add it to the RaxanWebPage class
        RaxanWebPage::addMethod('isUserLogin',array($this,'loginCheck')); // add a custom method to the page
        RaxanWebPage::addProperty('userAccessPermission','rwd');    // add a custom property to the page

        // add method to RaxanElement
        RaxanElement::addMethod('showUserInfo',array($this,'bindUserInfo'));
    }

    public function login($name, $password){
        // do something here
    }

    public function loginCheck($name){
        // do something here
    }

    public function bindUserInfo() {
        // do something here
    }
?&gt;
</code></pre>

<p>To use the new methods, you must first load the plugin before calling the methods:</p>

<pre><code class="php">&lt;?php

    // ... web page ...

    protected function _config() {
        $this-&gt;loadPlugin('network-connector'); // load plugin
    }

    // login view
    protected function _loginView() {
        $this-&gt;appendView('loggin.html');
    }

    protected function _authorize() {
        $this-&gt;loginStatus = $this-&gt;isUserLogin($this-&gt;userName);
        if ($this-&gt;loginStatus==false) {
            $this-&gt;redirectToView('login'); //redirect to login view
        }
    }

    // login event handler
    protected function processLogin($e) {
        $uid = $this-&gt;post-&gt;textVal('user');
        $pwd = $this-&gt;post-&gt;textVal('password');
        $loginOk = $this-&gt;networkUserLogin($uid, $pwd); // process user login
        if ($loginOk) $this-&gt;redirectToView('index');
        else $this-&gt;flashmsg('Login failed','fade','rax-box error');
    }

?&gt;
</code></pre>

<h3>System Events</h3>

<p>The following is a list of available system-events that can be used when a plugin:</p>

<ul>
<li><strong>system_init</strong> - Triggered after the system configuration files has being loaded</li>
<li><strong>system_error</strong> - Triggered when an error is not handled by the developer</li>
<li><strong>session_init</strong> - Triggered after the session storage class has being initialized. See the session.data.storage <a href="custom-config.html">config option</a></li>
<li><p><strong>data_connection</strong> - Triggered before a data connection is created. This event can be used to create custom data connectors by returning the an object to the event caller:</p>

<pre><code class="php">&lt;?php
    // custom data connection plugin
    protected function data_connection($e,$args){
        $dsn = $args(0);
        $user = $args(1);
        $password = $args(2);
        $attribs = $args(3);
        if (substr($dsn,0,11)=='custom-dsn:') {
            // do something - code to connect $conn to data source goes here
            return $conn;
        }
    }
?&gt;
</code></pre>

<p>To connect to the custom data source you can use the Raxan::connect() method:</p>

<pre><code class="php">&lt;?php
    protected function _load() {
        $db = $this-&gt;Raxan-&gt;connect('custom-dsn: server=localhost','user','password',true);
    }
?&gt;
</code></pre></li>
<li><p><strong>page_config</strong> - Triggered after web page _config event handler</p></li>
<li><strong>page_init</strong> - Triggered after web page _init event handler</li>
<li><p><strong>page_authorize</strong> - Triggered after web page _authorized event handler.</p>

<pre><code class="php">&lt;?php
    protected function page_authorize($e,$page){
        // code to validate user goes here
        if (!$isLogin) $page-&gt;redirectTo('login.php'); // redirect user to login page
        else if(!$isAuthorized) return false; // deny access to page
    }
?&gt;
</code></pre></li>
<li><p><strong>page_load</strong> - Triggered after web page _load event handler</p></li>
<li><strong>page_prerender</strong> - Triggered after web page _prerender event handler</li>
<li><strong>page_postrender</strong> - Triggered after web page _postrender event handler</li>
<li><strong>page_reply</strong> - Triggered after web page _reply event handler</li>
</ul>

<hr class="clear" />

<p align="right">Up Next: <a href="data-sanitization.html" title="Data Sanitization">Data Sanitization</a> </p>
</div>
            
            <div id="footer" class="container c48 rax-active-pal round rax-glossy">
                <ul class="clearfix">
                    <li><a href="index.html">Overview</a></li>
                    <li><a href="features.html">Features</a></li>
                    <li><a href="new-features.html">What's new</a></li>
                    <li><a href="table-of-contents.html" title="Table of Content">Contents</a></li>
                    <li><a href="../examples">Examples</a></li>
                </ul>
            </div>
        </div>
    </div>
</body>

</html>

